home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / gui / bgui11b.lha / docs / bgui.doc < prev    next >
Encoding:
Text File  |  1994-12-02  |  11.2 KB  |  312 lines
  1.  
  2.            $RCSfile: bgui.doc,v $
  3.         Description: bgui.library documentation.
  4.           Copyright: (C) Copyright 1994 Jaba Development.
  5.                      (C) Copyright 1994 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8.             $Author: jaba $
  9.           $Revision: 1.2 $
  10.               $Date: 1994/07/16 18:18:43 $
  11. -------------------------------------------------------------------------------
  12.  
  13. TABLE OF CONTENTS
  14.  
  15. bgui.library/BGUI_GetClassPtr
  16. bgui.library/BGUI_NewObjectA
  17. bgui.library/BGUI_RequestA
  18. bgui.library/BGUI_Help
  19. bgui.library/BGUI_LockWindow
  20. bgui.library/BGUI_UnlockWindow
  21. bgui.library/BGUI_DoGadgetMethodA
  22.  
  23. bgui.library/BGUI_GetClassPtr                      bgui.library/BGUI_GetClassPtr
  24.  
  25.     NAME
  26.         BGUI_GetClassPtr -- Obtain a pointer to a BGUI class.
  27.  
  28.     SYNOPSIS
  29.         class = BGUI_GetClassPtr( classID )
  30.         D0                        D0
  31.  
  32.         Class *BGUI_GetClassPtr( ULONG );
  33.  
  34.     FUNCTION
  35.         This function is ment to provide class writers an  easy way  to obtain a
  36.         pointer to one of the bgui.library classes. The pointer returned by this
  37.         routine may _only_ be used to subclass or to obtain objects from. Either
  38.         reading from or writing to the class structure is not allowed.
  39.  
  40.     INPUTS
  41.         classID         - The numeric ID of the class you need.
  42.  
  43.     RESULT
  44.         A pointer to the requested class or NULL if the call was  unsuccessfull.
  45.  
  46.     BUGS
  47.         None known.
  48.  
  49.     SEE ALSO
  50.         libraries/bgui.h
  51.  
  52. bgui.library/BGUI_NewObjectA                        bgui.library/BGUI_NewObjectA
  53.  
  54.     NAME
  55.         BGUI_NewObjectA -- Get an object from a class.
  56.         BGUI_NewObject -- Varargs version.
  57.  
  58.     SYNOPSIS
  59.         object = BGUI_NewObjectA( classID, tags )
  60.         D0                        D0       A0
  61.  
  62.         Object *BGUI_NewObjectA( ULONG, struct TagItem * )
  63.  
  64.         object = BGUI_NewObject( classID, tag1, ... )
  65.  
  66.         Object *BGUI_NewObject( ULONG, Tag, ... )
  67.  
  68.     FUNCTION
  69.         This routine is a replacement routine for intuition's NewObjectA() call.
  70.         It is an easy way to obtain an object from any of the  BGUI classes. You
  71.         pass it a classID and some create time attributes  and the  routine will
  72.         return you a pointer to the created object.
  73.  
  74.     INPUTS
  75.         classID - The numeric ID of the class.
  76.  
  77.         tags    - A set of create-time attributes  which will be passed onto the
  78.                   class of which the object is created.
  79.  
  80.     RESULT
  81.         A pointer to the created object or NULL if an error occured.
  82.  
  83.     BUGS
  84.         None known.
  85.  
  86.     SEE ALSO
  87.         intuition.library/NewObjectA(), libraries/bgui.h
  88.  
  89. bgui.library/BGUI_RequestA                            bgui.library/BGUI_RequestA
  90.  
  91.     NAME
  92.         BGUI_RequestA -- Put up a requester.
  93.         BGUI_Request -- Varargs version.
  94.  
  95.     SYNOPSIS
  96.         gadid = BGUI_RequestA( win, req, args )
  97.         D0                     A0   A1   A2
  98.  
  99.         ULONG BGUI_RequestA( struct Window *, struct bguiRequest *, ULONG * )
  100.  
  101.         gadid = BGUI_Request( win, req, arg1, ... )
  102.  
  103.         ULONG BGUI_Request( struct Window *, struct bguiRequest *, ULONG, ... )
  104.  
  105.     FUNCTION
  106.         To  put  up  a  requester.   It  is typically the  same  as  intuition's
  107.         EasyRequestArgs() only this routine allows you to put in InfoClass style
  108.         command sequences in the body text.
  109.  
  110.     INPUTS
  111.         win     - A pointer to the window on which the requester will open. This
  112.                   may be NULL.
  113.  
  114.         req     - A pointer to  an  initialized  bguiRequest  structure.    This
  115.                   structure is  simular  to  intuition's  EasyStruct  structure.
  116.                   It is used to control the  general  look of the requester. The
  117.                   structure is  initialized  with the following data:
  118.  
  119.                   br_Flags        - This  field can contain any of the following
  120.                                     flags:
  121.  
  122.                                     BREQF_CENTERWINDOW
  123.                                         This  will center the requester over the
  124.                                         window 'win' if a  valid  pointer  to  a
  125.                                         window is passed.
  126.  
  127.                                     BREQF_LOCKWINDOW
  128.                                         This will  disable  the window  on which
  129.                                         the requester appears from receiving any
  130.                                         IDCMP messages.   Also a busy pointer is
  131.                                         set on that window.   NOTE: ' win'  must
  132.                                         point to a window for this to work.
  133.  
  134.                                     BREQF_NO_PATTERN
  135.                                         This will suppress the backfill pattern.
  136.  
  137.                                     BREQF_XEN_BUTTONS
  138.                                         When set this flag will make the buttons
  139.                                         framing appear as XEN style framing.
  140.  
  141.                                     BREQF_AUTO_ASPECT
  142.                                         When set all  the  requester  will  make
  143.                                         some aspect  ratio dependant  changes to
  144.                                         the GUI like thin/thick frames etc.
  145.  
  146.                   br_Title        - A pointer to the title of the requester.  If
  147.                                     this is NULL the title of the window is used
  148.                                     if one is present.  In the  last  case "BGUI
  149.                                     Request"  or  it's  localized  equivalent is
  150.                                     used.
  151.  
  152.  
  153.                   br_GadgetFormat - A  pointer to the gadget label string.   The
  154.                                     gadget  labels   are   truncated  by  a  '|'
  155.                                     character. I.E "OK|Cancel" will give  you  a
  156.                                     "OK" and a "Cancel" gadget.
  157.  
  158.                   br_TextFormat   - A printf-style formatting  string which  may
  159.                                     also   contain   InfoClass   style   command
  160.                                     sequences.
  161.  
  162.                   br_ReqPos       - The  position  at which   the requester will
  163.                                     be opened.   There are three possibilities:
  164.  
  165.                                     POS_CENTERSCREEN
  166.                                     POS_CENTERMOUSE
  167.                                     POS_TOPLEFT
  168.  
  169.                                     It should be obvious what  they mean.  NOTE:
  170.                                     The  BREQF_CENTERWINDOW  flag  will override
  171.                                     this setting.
  172.  
  173.                   br_Underscore   - With this field you  can  set the  character
  174.                                     which preceedes the character  to underline.
  175.                                     The  underlined  character  will  be the key
  176.                                     which activates the gadget.
  177.  
  178.                   br_Reserved0    - These fields  are  for  future expansion and
  179.                                     _must_ be zero'd.
  180.  
  181.                   br_Screen       - Here you can optionally  specify the  Screen
  182.                                     on  which  the  requester  must  appear.  By
  183.                                     default  the Window it's Screen is used if a
  184.                                     valid Window pointer is given.  If no Window
  185.                                     is given then this Screen is used.  If  this
  186.                                     field is NULL the  default Public  Screen is
  187.                                     used.
  188.  
  189.                   br_Reserved1    - These fields  are  for  future expansion and
  190.                                     _must_ be zero'd.
  191.  
  192.         args    - A pointer to an array of arguments for the  C-style formatting
  193.                   codes.
  194.  
  195.     RESULT
  196.         1, 2, 3, 4 ....., 0 You will be returned a value ranging  from  0 to the
  197.         amount of gadgets minus one.     NOTE: The right most gadget will always
  198.         return 0.
  199.  
  200.     BUGS
  201.         This routine  really  should support underscored characters and keyboard
  202.         short cuts.
  203.  
  204.     SEE ALSO
  205.         intuition.library/EasyRequestArgs(), intuition/intuition.h,
  206.         libraries/bgui.h, infoclass.doc
  207.  
  208. bgui.library/BGUI_Help                                    bgui.library/BGUI_Help
  209.  
  210.     NAME
  211.         BGUI_Help -- Put up a simple synchronus amigaguide help file.
  212.  
  213.     SYNOPSIS
  214.         success = BGUI_Help( win, file, node, line )
  215.         D0                   A0   A1    A2    D0
  216.  
  217.         BOOL BGUI_Help( struct Window *, UBYTE *, UBYTE *, ULONG )
  218.  
  219.     FUNCTION
  220.         To show additional online-help using the amigaguide system.
  221.  
  222.     INPUTS
  223.         win     - A pointer to the window which shows the help.
  224.  
  225.         name    - A pointer to the full path name of the amigaguide file.
  226.  
  227.         node    - A pointer to the node name to display.
  228.  
  229.         line    - The line number to display.
  230.  
  231.     RESULT
  232.         TRUE uppon success and FALSE if something went wrong.
  233.  
  234.     BUGS
  235.         None known.
  236.  
  237.     SEE ALSO
  238.         amigaguide.library/OpenAmigaGuideA()
  239.  
  240. bgui.library/BGUI_LockWindow                        bgui.library/BGUI_LockWindow
  241.  
  242.     NAME
  243.         BGUI_LockWindow -- Disable a window from receiving IDCMP.
  244.  
  245.     SYNOPSIS
  246.         lock = BGUI_LockWindow( win )
  247.         D0                      A0
  248.  
  249.         APTR BGUI_LockWindow( struct Window * )
  250.  
  251.     FUNCTION
  252.         To disable a window from receiving IDCMP messages on  it's message port.
  253.         This is done by putting  up an  invisible  requester and a  busy pointer
  254.         same as the workbench uses. The only thing possible with  locked windows
  255.         is moving it with the dragbar and depth gadget.
  256.  
  257.     INPUTS
  258.         win     - A pointer to the window to lock.
  259.  
  260.     RESULT
  261.         lock will point to some private data if successfull or NULL if not.
  262.  
  263.     BUGS
  264.         None know.
  265.  
  266.     SEE ALSO
  267.         bgui.library/BGUI_UnlockWindow()
  268.  
  269. bgui.library/BGUI_UnlockWindow                    bgui.library/BGUI_UnlockWindow
  270.  
  271.     NAME
  272.         BGUI_UnlockWindow -- Enable a window from receiving IDCMP.
  273.  
  274.     SYNOPSIS
  275.         BGUI_UnlockWindow( lock )
  276.                            A0
  277.  
  278.         VOID BGUI_UnlockWindow( APTR )
  279.  
  280.     FUNCTION
  281.         To enable a window to receive IDCMP messages on  it's message port. This
  282.         routine must be used to 'unlock' windows locked with BGUI_LockWindow().
  283.  
  284.     INPUTS
  285.         lock    - A pointer to the data returned by BGUI_LockWindow().  This may
  286.                   be NULL.
  287.  
  288.     RESULT
  289.         The window will be unlocked.
  290.  
  291.     BUGS
  292.         None know.
  293.  
  294.     SEE ALSO
  295.         bgui.library/BGUI_LockWindow()
  296.  
  297. bgui.library/BGUI_DoGadgetMethodA            bgui.library/BGUI_DoGadgetMethodA
  298.  
  299.     **************************************************************************
  300.     This routine is the same as intuition's DoGadgetMethod() routine  with the
  301.     exception  that  this call is _simulated_ on systems running lower than OS
  302.     3.0.   I  have  not  yet  experienced problems with this routine  on these
  303.     systems but please keep in mind that it is basically a hack under 2.04.
  304.     **************************************************************************
  305.  
  306.     BUGS
  307.         This call is simulated on systems running lower than OS 3.0.  There is
  308.         no way to avoid this...
  309.  
  310.     SEE ALSO
  311.         intuition.library/DoGadgetMethod()
  312.